{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_ddvzzae"
   },
   "source": [
    "## Function Order in a Single File\n",
    "\n",
    "In the following code example, the functions are out of order, and the code will not compile. Try to fix this by rearranging the functions to be in the correct order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "graffitiCellId": "id_mp64xja",
    "graffitiConfig": {
     "executeCellViaGraffiti": "qb0wxcq_uywx522"
    }
   },
   "outputs": [],
   "source": [
    "#include <iostream>\n",
    "using std::cout;\n",
    "\n",
    "void OuterFunction(int i) \n",
    "{\n",
    "    InnerFunction(i);\n",
    "}\n",
    "\n",
    "void InnerFunction(int i) \n",
    "{\n",
    "    cout << \"The value of the integer is: \" << i << \"\\n\";\n",
    "}\n",
    "\n",
    "int main() \n",
    "{\n",
    "    int a = 5;\n",
    "    OuterFunction(a);\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_qb0wxcq"
   },
   "source": [
    "<span class=\"graffiti-highlight graffiti-id_qb0wxcq-id_uywx522\"><i></i><button>Compile & Execute</button></span> &nbsp; <span class=\"graffiti-highlight graffiti-id_qukoro0-id_zjkml9y\"><i></i><button>Show Solution</button></span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_4wc3hya",
    "graffitiConfig": {
     "rows": 6,
     "terminalId": "id_umc3wk2",
     "type": "terminal"
    }
   },
   "source": [
    "<i>Loading terminal (id_4wc3hya), please wait...</i>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_fjyw0lv"
   },
   "source": [
    "In the mini-project for the first half of the course, the instructions were very careful to indicate where each function should be placed, so you didn't run into the problem of functions being out of order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_k2u63tc"
   },
   "source": [
    "## Using a Header\n",
    "\n",
    "One other way to solve the code problem above (without rearranging the functions) would have been to declare each function at the top of the file. A function declaration is much like the first line of a function definition - it contains the return type, function name, and input variable types. The details of the function definition are not needed for the declaration though.\n",
    "\n",
    "To avoid a single file from becomming cluttered with declarations and definitions for every function, it is customary to declare the functions in another file, called the header file. In C++, the header file will have filetype `.h`, and the contents of the header file must be included at the top of the `.cpp` file. See the following example for a refactoring of the code above into a header and a cpp file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "graffitiCellId": "id_07oaumc"
   },
   "outputs": [],
   "source": [
    "// The header file with just the function declarations.\n",
    "// When you click the \"Run Code\" button, this file will\n",
    "// be saved as header_example.h.\n",
    "#ifndef HEADER_EXAMPLE_H\n",
    "#define HEADER_EXAMPLE_H\n",
    "\n",
    "void OuterFunction(int);\n",
    "void InnerFunction(int);\n",
    "\n",
    "#endif"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "graffitiCellId": "id_0rusb8f",
    "graffitiConfig": {
     "executeCellViaGraffiti": "mdf24jj_unu9oj8"
    }
   },
   "outputs": [],
   "source": [
    "// The contents of header_example.h are included in \n",
    "// the corresponding .cpp file using quotes:\n",
    "#include \"header_example.h\"\n",
    "\n",
    "#include <iostream>\n",
    "using std::cout;\n",
    "\n",
    "void OuterFunction(int i) \n",
    "{\n",
    "    InnerFunction(i);\n",
    "}\n",
    "\n",
    "void InnerFunction(int i) \n",
    "{\n",
    "    cout << \"The value of the integer is: \" << i << \"\\n\";\n",
    "}\n",
    "\n",
    "int main() \n",
    "{\n",
    "    int a = 5;\n",
    "    OuterFunction(a);\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_mdf24jj"
   },
   "source": [
    "<span class=\"graffiti-highlight graffiti-id_mdf24jj-id_unu9oj8\"><i></i><button>Compile & Execute</button></span> &nbsp; <span class=\"graffiti-highlight graffiti-id_c4cl1ej-id_dpjr6gv\"><i></i><button>Explain</button></span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_017mcyj",
    "graffitiConfig": {
     "rows": 6,
     "terminalId": "id_6svhh4d",
     "type": "terminal"
    }
   },
   "source": [
    "<i>Loading terminal (id_017mcyj), please wait...</i>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_tbutuxn"
   },
   "source": [
    "Notice that the code from the first example was fixed without having to rearrange the functions! In the code above, you might also have noticed several other things:\n",
    "- The function declarations in the header file don't need variable names, just variable types. You can put names in the declaration, however, and doing this often makes the code easier to read.\n",
    "- The `#include` statement for the header used quotes `\" \"` around the file name, and not angle brackets `<>`. We have stored the header in the same directory as the `.cpp` file, and the quotes tell the preprocessor to look for the file in the same directory as the current file - not in the usual set of directories where libraries are typically stored.\n",
    "- Finally, there is a preprocessor directive:\n",
    "  ```cpp\n",
    "  #ifndef HEADER_EXAMPLE_H\n",
    "  #define HEADER_EXAMPLE_H\n",
    "  ``` \n",
    "  at the top of the header, along with an `#endif` at the end. This is called an \"include guard\". Since the header will be included into another file, and `#include` just pastes contents into a file, the include guard prevents the same file from being pasted multiple times into another file. This might happen if multiple files include the same header, and then are all included into the same `main.cpp`, for example. \n",
    "  The `ifndef` checks if `HEADER_EXAMPLE_H` has not been defined in the file already. If it has not been defined yet, then it is defined with `#define HEADER_EXAMPLE_H`, and the rest of the header is used. If `HEADER_EXAMPLE_H` has already been defined, then the preprocessor does not enter the `ifndef` block.\n",
    "  **Note:** There are other ways to do this. Another common way is to use an `#pragma once`preprocessor directive, but we won't cover that in detail here. See [this Wikipedia article](https://en.wikipedia.org/wiki/Include_guard) for examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_s5grbt2"
   },
   "source": [
    "## Practice\n",
    "\n",
    "In the following two cells, there is a blank header file and a short program that won't compile due to the functions being out of order. The code should take a vector of `int`s, add 1 to each of the vector entries, and then print the sum over the vector entries.\n",
    "\n",
    "\n",
    "Without rearranging the functions in the main .cpp file, add some function declarations to the header file to fix this problem. Don't forget to include the \"header_practice.h\" file in your `.cpp` file!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "graffitiCellId": "id_7psmxgg"
   },
   "outputs": [],
   "source": [
    "// This file will be saved as \"header_practice.h\"\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "graffitiCellId": "id_yh887ja",
    "graffitiConfig": {
     "executeCellViaGraffiti": "q1rlo5o_afzz8cc"
    }
   },
   "outputs": [],
   "source": [
    "#include <iostream>\n",
    "#include <vector>\n",
    "using std::vector;\n",
    "using std::cout;\n",
    "\n",
    "\n",
    "int IncrementAndComputeVectorSum(vector<int> v) \n",
    "{\n",
    "    int total = 0;\n",
    "    AddOneToEach(v);\n",
    "\n",
    "    for (auto i: v) {\n",
    "        total += i;\n",
    "    }\n",
    "    return total;\n",
    "}\n",
    "\n",
    "void AddOneToEach(vector<int> &v) \n",
    "{\n",
    "    // Note that the function passes a reference to v\n",
    "    // and the for loop below uses references to \n",
    "    // each item in v. This means the actual\n",
    "    // ints that v holds will be incremented.\n",
    "    for (auto& i: v) {\n",
    "        i++;\n",
    "    }\n",
    "}\n",
    "\n",
    "int main() \n",
    "{\n",
    "    vector<int> v{1, 2, 3, 4};\n",
    "    int total = IncrementAndComputeVectorSum(v);\n",
    "    cout << \"The total is: \" << total << \"\\n\";\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_q1rlo5o"
   },
   "source": [
    "<span class=\"graffiti-highlight graffiti-id_q1rlo5o-id_afzz8cc\"><i></i><button>Compile & Execute</button></span> &nbsp; <span class=\"graffiti-highlight graffiti-id_y33dmb2-id_k1yr73f\"><i></i><button>Show Solution</button></span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "graffitiCellId": "id_qk25dsd",
    "graffitiConfig": {
     "rows": 12,
     "terminalId": "id_qk25dsd",
     "type": "terminal"
    }
   },
   "source": [
    "<i>Loading terminal (id_qk25dsd), please wait...</i>"
   ]
  }
 ],
 "metadata": {
  "graffiti": {
   "firstAuthorId": "813558546",
   "id": "id_w5gmfte",
   "language": "EN"
  },
  "kernelspec": {
   "display_name": "C++17",
   "language": "C++17",
   "name": "xeus-cling-cpp17"
  },
  "language_info": {
   "codemirror_mode": "text/x-c++src",
   "file_extension": ".cpp",
   "mimetype": "text/x-c++src",
   "name": "c++",
   "version": "-std=c++17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
